package fm.last
{
    import fm.last.api.*;
    
    /**
     * 
     * Last.fm Service.
     * <br/>
     * Each API call is given an <code>onComplete</code> and an <code>onError</code> callback functions along with correspong API parameters.
     * <code>onComlete</code> callback function handles the sucessful response.
     * <code>onError</code> callback function handles any error including last.fm error response (http 400), however the
     * content of error message can not be retrieved.  
     * <br/>
     * The signature of an <code>onComlete</code> callback is <code>function onComplete(response:XML):void</code>, where <code>response</code> is 
     * the request result of Last.fm's API.
     * The signature of an <code>onError</code> callback is <code>function onError(e:ErrorEvent):void</code>,
     * whrere the <code>ErrorEvent e</code> could be in type of 
     * <code>IOErrorEvent.IO_ERROR</code> or 
     * <code>SecurityErrorEvent.SECURITY_ERROR</code>.
     * <br/>
     * 
     * Usage:
     * <pre>
     * package {
     *
     *  
     *    import fm.last.*;
     *    import fm.last.api.*;
     *    import fm.last.error.*;
     * 
     *    import flash.display.Sprite;
     *    import flash.events.*;
     *    import flash.net.*;
     * 
     *    public class LastFmServiceExample1 extends Sprite {
     * 
     *       public function LastFmServiceExample1() 
     *       {
     *          // example for http://www.last.fm/api/show?service=119
     *          var lastfm:LastFmService = new LastFmService("an_api_key");
     *          lastfm.artist.getSimilar(onComplete, onError, "cher");
     *          lastfm.artist.getSimilar(onComplete, onError, "No_Such_Artist");
     *       }
     *    
     *       private function onComplete(response:XML):void 
     *       {
     *          trace(response);
     *       }
     *  
     *       private function onError(e:ErrorEvent):void 
     *       {
     *          trace(e.toString());
     *       }
     *    }
     * }            
     * </pre>
     * 
     * Here is an example to show how to use auth.getSession and those APIS which require authentication.
     * 
     * <pre>
     * package {
     * 
     *    import fm.last.*;
     *    import fm.last.api.*;
     *    import fm.last.error.*;
     * 
     *    import flash.display.Sprite;
     *    import flash.events.*;
     *    import flash.net.*;
     * 
     *    public class LastFmServiceExample2 extends Sprite {
     * 
     *       public function LastFmServiceExample2() 
     *       {
     *          // example for http://www.last.fm/api/show?service=125
     *          var lastfm:LastFmService = new LastFmService("an_api_key", "a_secret");
     *          lastfm.auth.getSession(onGetSession, onError, "a_token");          
     *       }
     *    
     *       private function onGetSession(response:XML):void 
     *       {
     *          var sessionKey:String = response.session.key;
     *          
     *          var lastfmInSession:LastFmService = new LastFmService("an_api_key", "a_secret", sessionKey);
     *          lastfmInSession.library.addArtist(onComplete, onError, "Björk");
     *       }
     *  
     *       private function onComplete(response:XML):void 
     *       {
     *          trace(response);
     *       }
     * 
     *       private function onError(e:ErrorEvent):void 
     *       {
     *          trace(e.toString());
     *       }
     *    }
     * }            
     * </pre>
     */    
    final public class LastFmService
    {           
        /** agent object */
        private var agent:Agent = null;                                            
        /** @private */
        private var _albumAPI:AlbumAPI = null;
        /** @private */
        private var _artistAPI:ArtistAPI = null;
        /** @private */
        private var _authAPI:AuthAPI = null;
        /** @private */
        private var _eventAPI:EventAPI = null;
        /** @private */
        private var _geoAPI:GeoAPI = null;
        /** @private */
        private var _groupAPI:GroupAPI = null;
        /** @private */
        private var _libraryAPI:LibraryAPI = null;
        /** @private */
        private var _playlistAPI:PlaylistAPI = null;
        /** @private */
        private var _radioAPI:RadioAPI = null;
        /** @private */        
        private var _tagAPI:TagAPI = null;
        /** @private */
        private var _tasteometerAPI:TasteometerAPI = null;
        /** @private */
        private var _trackAPI:TrackAPI = null;
        /** @private */
        private var _userAPI:UserAPI = null;
        /** @private */
        private var _venueAPI:VenueAPI = null;
        
        /**
         * construct a LastFmservice
         */ 
        public function LastFmService(api_key:String, secret:String=null, sk:String=null) 
        {            
            agent = new Agent(api_key, secret, sk);                    
        }                

        /** get albumb API */        
        public function get album():AlbumAPI 
        { 
            if (_albumAPI == null) _albumAPI = new AlbumAPI(agent);
            return _albumAPI;
        }
        
        /** get artist API */
        public function get artist():ArtistAPI 
        { 
            if (_artistAPI == null) _artistAPI = new ArtistAPI(agent);
            return _artistAPI;
        }
        
        /** get auth API */
        public function get auth():AuthAPI 
        { 
            if (_authAPI == null) _authAPI = new AuthAPI(agent);
            return _authAPI;
        }
        
        /** get event API */
        public function get event():EventAPI 
        { 
            if (_eventAPI == null) _eventAPI = new EventAPI(agent);
            return _eventAPI;
        }
        
        /** get geo API */
        public function get geo():GeoAPI 
        { 
            if (_geoAPI == null) _geoAPI = new GeoAPI(agent);
            return _geoAPI;
        }
        
        /** get group API */
        public function get group():GroupAPI 
        { 
            if (_groupAPI == null) _groupAPI = new GroupAPI(agent);
            return _groupAPI;
        }
        
        /** get library API */
        public function get library():LibraryAPI 
        { 
            if (_libraryAPI == null) _libraryAPI = new LibraryAPI(agent);
            return _libraryAPI;
        }
        
        /** get playlist API */
        public function get playlist():PlaylistAPI 
        { 
            if (_playlistAPI == null) _playlistAPI = new PlaylistAPI(agent);
            return _playlistAPI;
        }
        
        /** get radio API */
        public function get radio():RadioAPI 
        { 
            if (_radioAPI == null) _radioAPI = new RadioAPI(agent);
            return _radioAPI;
        }
        
        /** get tag API */
        public function get tag():TagAPI 
        { 
            if (_tagAPI == null) _tagAPI = new TagAPI(agent);
            return _tagAPI;
        }
        
        /** get taseteometer API */
        public function get tasteometer():TasteometerAPI 
        { 
            if (_tasteometerAPI == null) _tasteometerAPI = new TasteometerAPI(agent);
            return _tasteometerAPI;
        }
        
        /** get track API */
        public function get track():TrackAPI 
        { 
            if (_trackAPI == null) _trackAPI = new TrackAPI(agent);
            return _trackAPI;
        }
        
        /** get user API */
        public function get user():UserAPI 
        { 
            if (_userAPI == null) _userAPI = new UserAPI(agent);
            return _userAPI;
        }
        
        /** get venue API */
        public function get venue():VenueAPI 
        { 
            if (_venueAPI == null) _venueAPI = new VenueAPI(agent);
            return _venueAPI;
        }
                
    }
}